fix(nightly): refresh the App token across stages; a lost watch is a driver error - #578

Summary

The nightly release driver runs for hours on one GitHub App installation token that lives 60 minutes (since 6f5f95e, 2026-10-23). Every scheduled night from 10-24 to 11-04 died at the 60-minute mark with HTTP 401: Bad credentials while watching the Stage 3 Heart integrate run, and paged "Stage 3 failed" although that run passed on most nights. No nightly reached the readiness gate after the 2026-10-22 anchor; the 11-01 release was manual. NIGHTLY_RELEASES is false since 2026-11-04 until this lands.

This obeys the token policy as written ("mint it right before a long loop, not at the top of the job") with no PAT and the same four permissions:

• bin/gh_app_token.py — stdlib + openssl mint of a fresh installation token; prints only the token, never logs the key or JWT.
• agents/conductors/release/_nightly_lib.sh — refresh_gh_token re-mints once the token is 45 min old (no-op without App credentials, so local runs on a personal gh are unchanged); await_run polls a run every minute, refreshing as it goes, and returns 4 after five consecutive failed reads.
• agents/conductors/release/nightly.sh — refresh before every dispatch, download, read and the anchor write; a watch that still loses its credentials pages as a driver error (exit 1, workflow outcome driver-error), never as a stage failure. Step 6 uses notify rather than page on that path because the live release may have published.
• .github/workflows/nightly-release.yml — the driver step receives APP_CLIENT_ID / APP_PRIVATE_KEY for re-minting only; the initial mint step and the OUTCOME CONTRACT are unchanged.

Fixes #577.

API Changes

None. No library or public Python API is touched; the driver's exit-code contract gains one documented meaning for exit 1 (a lost watch). dispatch_and_await gains return code 4 (internal to the driver).

Test Plan

• python3 -m pytest -q tests/test_gh_app_token.py tests/test_nightly_await.py tests/test_activity_gate.py — 23 passed
• python3 -m pytest -q -x (whole Brain suite) — 1558 passed, 1 skipped
• bash -n on the driver and the new lib
• Witness (after merge, before re-arming): one manual nightly-release.yml dispatch with dry_run=true whose log shows Stage 2 and Stage 3 complete, no HTTP 401, and step 5 — readiness gate reached (Heart will likely be STALE, so it ends at exit 3 — that is the gate, not the bug). Then set NIGHTLY_RELEASES=true.

Decisions flagged for review

• The token request names the Variables permission actions_variables, matching the installation's own name (e0f88ca, 2026-10-23) and what create-github-app-token sends. If GitHub rejects it (HTTP 422 in the mint's stderr), the dry-run Witness will show it; the constant and the parity test change together.
• The App private key now enters the driver step's environment. The same job already holds it for the mint action; the driver is deterministic shell with no tracing and never echoes its environment.

Generated by the PyAutoLabs agent workflow.

🤖 Generated with Claude Code